Skip to content

Document explicit extraction mapping file selection - #1345

Open
xuu33030 wants to merge 1 commit into
python-babel:masterfrom
xuu33030:docs/1063-explicit-mapping
Open

xuu33030 wants to merge 1 commit into
python-babel:masterfrom
xuu33030:docs/1063-explicit-mapping

Conversation

@xuu33030

Copy link
Copy Markdown

Summary

The mapping documentation describes INI and TOML syntax, but does not show how to select a configuration file. This leaves readers unsure whether a particular filename is required or whether pyproject.toml is loaded automatically.

  • Show pybabel extract -F examples for babel.cfg, babel.toml, and pyproject.toml.
  • Explain explicit selection, the default Python-only mapping, and filename-based TOML/INI handling.
  • Correct the introduction to include the built-in JavaScript extractor.

The existing sections already describe built-in extractors, common options, and TOML syntax; this fills the remaining invocation gap. No runtime behavior changes.

Closes #1063.

Validation

On macOS with CPython 3.13.5, after importing the repository's CLDR 48.2 data:

  • python -m pytest -q tests: 6502 passed, 1174 skipped, 1 xfailed. Skips include unavailable pytz, setuptools, and benchmark dependencies, plus platform/deprecation-specific cases. One existing pytest parametrization deprecation warning.
  • python -m pytest -q tests/messages: 383 passed, 1 skipped.
  • Extracted the three new CLI commands and corresponding INI/TOML examples directly from the documentation, then ran them against temporary Python and JavaScript files. Verified the resulting POT messages. Also verified that a pyproject.toml ignore mapping has no effect without -F and takes effect when explicitly selected. These were local behavioral checks, not new committed tests.
  • git diff --check: passed.
  • python -m sphinx -b html -W --keep-going docs <output>: not clean on either the unchanged base or this branch. Both report the same five existing diagnostics (JavaScript extractor docstring indentation and unresolved links in dates/dev/messages); no new diagnostic was introduced.

The full multi-version/platform CI matrix was not run locally.

AI assistance disclosure: this documentation change and local verification were prepared with Hermes Agent assistance.

@akx akx left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thank you!

@codecov

codecov Bot commented Sep 18, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.37%. Comparing base (6ba6701) to head (e5db05f).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files
@@           Coverage Diff           @@
##           master    #1345   +/-   ##
=======================================
  Coverage   93.37%   93.37%           
=======================================
  Files          27       27           
  Lines        4919     4919           
=======================================
  Hits         4593     4593           
  Misses        326      326           
Flag Coverage Δ
macos-14-3.10 92.45% <ø> (ø)
macos-14-3.11 92.39% <ø> (ø)
macos-14-3.12 92.60% <ø> (ø)
macos-14-3.13 92.60% <ø> (ø)
macos-14-3.14 92.57% <ø> (ø)
macos-14-3.15 92.57% <ø> (ø)
macos-14-3.8 92.33% <ø> (ø)
macos-14-3.9 92.39% <ø> (ø)
macos-14-pypy3.10 92.45% <ø> (ø)
ubuntu-24.04-3.10 92.47% <ø> (ø)
ubuntu-24.04-3.11 92.41% <ø> (ø)
ubuntu-24.04-3.12 92.62% <ø> (ø)
ubuntu-24.04-3.13 92.62% <ø> (ø)
ubuntu-24.04-3.14 92.60% <ø> (ø)
ubuntu-24.04-3.15 92.60% <ø> (ø)
ubuntu-24.04-3.8 92.35% <ø> (ø)
ubuntu-24.04-3.9 92.41% <ø> (ø)
ubuntu-24.04-pypy3.10 92.47% <ø> (ø)
windows-2022-3.10 92.47% <ø> (ø)
windows-2022-3.11 92.40% <ø> (ø)
windows-2022-3.12 92.61% <ø> (ø)
windows-2022-3.13 92.61% <ø> (ø)
windows-2022-3.14 92.59% <ø> (ø)
windows-2022-3.15 92.59% <ø> (ø)
windows-2022-3.8 92.44% <ø> (ø)
windows-2022-3.9 92.40% <ø> (ø)
windows-2022-pypy3.10 92.47% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@codspeed

codspeed Bot commented Sep 18, 2026

Copy link
Copy Markdown

Merging this PR will not alter performance

✅ 88 untouched benchmarks


Comparing xuu33030:docs/1063-explicit-mapping (e5db05f) with master (6ba6701)

Open in CodSpeed

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

doc: Missing documentation on configuration

2 participants